// -*- mode:c++ -*-
/*!
\page kdupdater_architecture KDUpdater - Architecture Overview

The key responsibility of the KDUpdater module is to fetch updates from a
predefined server and install it on the local system. The following block
diagram explains this.

\image html kdupdater_highlevelarch.png

Some important points to note

\li KD Updater would be a module within the client application. This means that
the KD Updater module would not be useful as an independent entity. It has to be
used within a Qt application.

\li Updates can be fetched over the public Internet. This is the reason why
secure sockets have to be used for all data transactions.

\li Updates are hosted on a server, and are served via HTTP or FTP protocols.
This means KD Updater would not have to provide any server software.

The design of KD Updater can be understood in two main parts

\li \subpage kdupdater_updateserverarch. This part of the design describes the
format and files used on the update server to describe the updates hosted on
it. 

\li \subpage kdupdater_updateclientarch. This part of the design describes how
the client (as in the Qt application that uses the KD Updater module) discovers
and installs updates available in the server.

*/

/**
\page kdupdater_updateserverarch KDUpdater - Update Server Architecture

The update server is a location where updates are hosted for clients to download and
install. KDUpdater doesnt impose any special server software on its users,
however it does specify a format in which updates are hosted on the update
server. The format describes the following aspects of update hosting

- Listing updates available in the server
- Describing meta information about each update like
    -# Name of the update
    -# Title of the update
    -# Description of the update
    -# Update dependencies
- Describing the basic minimum stuff that the client should have in-order to be
able to download and install updates from the server.
- Hosting the update itself. It must be noted here at this point that updates
can be made available for different operating system and hardware architectures.
There must be some way to describe that as well.

Before understanding the format, lets define some standard terms

\li \ref kdupdater_updatedirectory - This is a directory in the update-server within which
all updates are made available

\li \ref kdupdater_updatexml - This is an XML file that describes the updates available
within an \i UpdateDirectory.

\li \ref kdupdater_updatefile - This is a compressed file that contains an update.
Typically the file would contain some binary programs, configuration files and
an installation script called \i UpdateInstructionsXML

\li \ref kdupdater_updateinstructionsxml - This is an XML file contained within an \i
UpdateFile. This XML file describes all the actions that must be executed on
the client in order to install the update.

\section kdupdater_updatedirectory UpdateDirectory

UpdateDirectory is a folder in the server within which all the updates are
hosted. The UpdateDirectory is usually accessible from the outer world via HTTP
or FTP protocols. It is even possible to host the UpdateDirectory on the local
filesystem.

\htmlonly
<center><table border="0" width="80%"><tr>
<td bgcolor="#ddddff" width="20px"></td>
<td width="*"><strong>Definition:<br><font color="blue">
UpdateDirectory is a standard directory which can be used within the server
for hosting updates.
</font></strong></td></tr></table></center>
\endhtmlonly

\section kdupdater_updatexml UpdateXML

The UpdateDirectory must contain one XML file called Updates.xml. This file
contains information about one or more updates hosted in UpdateDirectory.
Against each update the following information fields are available

\li \b Name – Name of the update. Update names must be unique and must not have
spaces or special characters
\li \b Title – Human readable title of the update.
\li \b Description – A brief description of the update.
\li \b Version and Release date.
\li \b Dependencies – Names of the updates on which this update depends on. This
information will be used to evaluate a dependency tree. Care must be taken to
ensure that cyclic dependencies are not created.
\li \b Update \b file(s) – Names of the files hosted in the UpdateDirectory that
provide this update. 

Shown below is a sample UpdateXML file. 

\htmlonly
<pre>
<b>&lt;Updates&gt;</b>

  <span style='color: #7488ae'><i>&lt;!-- Meta information about the software application for </i></span>
<span style='color: #7488ae'><i>       which these updates are hosted --&gt;</i></span>
  <b>&lt;AppName&gt;</b>VTKDesigner2<b>&lt;/AppName&gt;</b>
  <b>&lt;AppVersion&gt;</b>2.0<b>&lt;/AppVersion&gt;</b>

  <b>&lt;CompatUpdate&gt;</b>
    <b>&lt;Level&gt;</b>4<b>&lt;/Level&gt;</b>
    <b>&lt;Description&gt;</b>Description of the compatibility level<b>&lt;/Description&gt;</b>
    <b>&lt;ReleaseDate&gt;</b>02/02/2008<b>&lt;/ReleaseDate&gt;</b>
    <b>&lt;UpdateFile</b><span style='color: #00892b'> platform-regex=</span><span style='color: #aa0000'>"Linux-i386"</span><b>&gt;</b>
        CompatUpdate-4-Linux-i386.kvz
    <b>&lt;/UpdateFile&gt;</b>
    <b>&lt;UpdateFile</b><span style='color: #00892b'> platform-regex=</span><span style='color: #aa0000'>"WindowsXP-i386"</span><b>&gt;</b>
        CompatUpdate-4-Win32-i386.kvz
    <b>&lt;/UpdateFile&gt;</b>
    <b>&lt;UpdateFile</b><span style='color: #00892b'> platform-regex=</span><span style='color: #aa0000'>"MacOSX-i386"</span><b>&gt;</b>
        CompatUpdate-4-Mac32-i386.kvz
    <b>&lt;/UpdateFile&gt;</b>
  <b>&lt;/CompatUpdate&gt;</b>

  <b>&lt;Update&gt;</b>
    <b>&lt;Name&gt;</b>ReportEditorPlugin<b>&lt;/Name&gt;</b>
    <b>&lt;Title&gt;</b>Report Editor Plugin<b>&lt;/Title&gt;</b>
    <b>&lt;Description&gt;</b>This plugin helps create reports<b>&lt;/Description&gt;</b>
    <b>&lt;Version&gt;</b>3<b>&lt;/Version&gt;</b>
    <b>&lt;ReleaseDate&gt;</b>02/02/2008<b>&lt;/ReleaseDate&gt;</b>
    <b>&lt;Dependencies&gt;</b>
      <b>&lt;DependsOn&gt;</b>GenericComponentFramework<b>&lt;/DependsOn&gt;</b>
      <b>&lt;DependsOn&gt;</b>MainWindowComponent<b>&lt;/DependsOn&gt;</b>
      <b>&lt;DependsOn&gt;</b>VisSystem<b>&lt;/DependsOn&gt;</b>
    <b>&lt;/Dependencies&gt;</b>
    <b>&lt;UpdateFile</b><span style='color: #00892b'> platform-regex=</span><span style='color: #aa0000'>"Linux-i386"</span><b>&gt;</b>REP-Linux-i386.kvz<b>&lt;/UpdateFile&gt;</b>
    <b>&lt;UpdateFile</b><span style='color: #00892b'> platform-regex=</span><span style='color: #aa0000'>"Linux-i386"</span><b>&gt;</b>REP-Win32-i386.kvz<b>&lt;/UpdateFile&gt;</b>
    <b>&lt;UpdateFile</b><span style='color: #00892b'> platform-regex=</span><span style='color: #aa0000'>"Linux-i386"</span><b>&gt;</b>REP-Mac32-i386.kvz<b>&lt;/UpdateFile&gt;</b>
  <b>&lt;/Update&gt;</b>

  <span style='color: #7488ae'><i>&lt;!-- More Update Entries --&gt;</i></span>

<b>&lt;/Updates&gt;</b>
</pre>
\endhtmlonly

Refer to \ref kdupdater_updatexml_fileformat for more information about the 
UpdateXML file format.

\htmlonly
<center><table border="0" width="80%"><tr>
<td bgcolor="#ddddff" width="20px"></td>
<td width="*"><strong>Definition:<br><font color="blue">
UpdateXML is a file within the UpdateDirectory whose filename is Update.xml. 
This file describes the updates available in the UpdateDirectory
</font></strong></td></tr></table></center>
\endhtmlonly

\section kdupdater_updatefile UpdateFile

UpdateFile is a compressed file that contains everything about a single update.
A typical update consists of one or more files that should be copied into the 
application directory(ies) and/or system directory(ies) during the installation 
of the update. All of these files have to be compressed into a single file and 
served as such; this single file is called UpdateFile.

\subsection kdupdater_updatefile1 Creating UpdateFiles

UpdateFile(s) can be created using the \c UFCreator tool. Suppose that we
wanted to provide an update for the ChartPlugin in our client application.

\htmlonly
<strong>Step 1: Create a UpdateFile directory </strong>
\endhtmlonly

First we create a directory into which we will copy/paste all the files 
required by the update. Shown below are the files that are needed for our
ChartPlugin update.

\htmlonly
<pre>
ChartPlugin-Linux32-i386/
ChartPlugin-Linux32-i386/libChartPlugin.so.2.1.0
ChartPlugin-Linux32-i386/UpdateInstructions.xml
ChartPlugin-Linux32-i386/ChartPlugin-2.1.0-Config.xml
</pre>
\endhtmlonly

\htmlonly
<strong>Step 2: Create the UpdateFile</strong>
\endhtmlonly

We now make use of the UFCreator tool to compress the ChartPlugin-Linux32-i386
directory into an UpdateFile. The command line to use is shown below

\htmlonly
<pre>
[user@localhost]$ ufcreator ChartPlugin-Linux32-i386
Source Directory = ChartPlugin-Linux32-i386
Compressed file  = ChartPlugin-Linux32-i386.kvz
ChartPlugin-Linux32-i386.kvz created
[user@localhost]$ 
</pre>
\endhtmlonly

\htmlonly
<strong>Step 3: Update the Updates.xml file</strong>
\endhtmlonly

The ChartPlugin-Linux32-i386.kvz file can then be copied into the UpdateDirectory,
and an additional entry as follows can be inserted into the Updates.xml file.

\htmlonly
<pre>
<b>&lt;Update&gt;</b>

    <b>&lt;Name&gt;</b>ChartPlugin<b>&lt;/Name&gt;</b>
    
    <b>&lt;Title&gt;</b>Chart Plugin<b>&lt;/Title&gt;</b>
    
    <b>&lt;Description&gt;</b>
        This plugin provides improved charting facility
    <b>&lt;/Description&gt;</b>
    
    <b>&lt;Version&gt;</b>2.1.0<b>&lt;/Version&gt;</b>
    
    <b>&lt;ReleaseDate&gt;</b>09/08/2009<b>&lt;/ReleaseDate&gt;</b>
    
    <b>&lt;UpdateFile</b><span style='color: #00892b'> platform-regex=</span><span style='color: #aa0000'>"Linux-i386"</span><b>&gt;</b>
        ChartPlugin-Linux32-i386.kvz
    <b>&lt;/UpdateFile&gt;</b>
    
<b>&lt;/Update&gt;</b>
</pre>
\endhtmlonly

\subsection kdupdater_updatefile2 Extracting UpdateFiles

Extracting UpdateFile(s) is made possible by the UFExtractor tool. Its
commandline usage is as shown below

\htmlonly
<pre>
[user@localhost]$ ufextractor ChartPlugin-Linux32-i386.kvz
Compressed file = ChartPlugin-Linux32-i386.kvz
Uncompressed directory = .
Uncompressed ./ChartPlugin-Linux32-i386/ChartPlugin-2.1.0-Config.xml
Uncompressed ./ChartPlugin-Linux32-i386/libChartPlugin.so.2.1.0
Uncompressed ./ChartPlugin-Linux32-i386/UpdateInstructions.xml
ChartPlugin-Linux32-i386.kvz extracted
[user@localhost]$ 
</pre>
\endhtmlonly

Before going to the next section, lets revisit the definition for UpdateFile

\htmlonly
<center><table border="0" width="80%"><tr>
<td bgcolor="#ddddff" width="20px"></td>
<td width="*"><strong>Definition:<br><font color="blue">
An UpdateFile is a compressed file that contains all the files and directories 
required for installing the update on the client. Each UpdateFile contains the 
file(s) required for installing that update. Update dependencies can be used to 
provide dependent files if needed
</font></strong></td></tr></table></center>
\endhtmlonly

\section kdupdater_updateinstructionsxml UpdateInstructionsXML

Among the files that make an update is a special file called 
UpdateInstructions.xml. This XML file describes the sequence of operations that 
must be performed on the client side to actually install the update. Note that 
the operations are performed after the UpdateFile has been downloaded and 
uncompressed in the client side. Each operation is described in terms of 

\li Operation name
\li Operation arguments
\li Error handling cues

Shown below is a sample UpdateInstructions.xml file

\htmlonly
<pre>
<b>&lt;UpdateInstructions&gt;</b>

  <span style='color: #7488ae'><i>&lt;!-- Meta information about the update for which the </i></span>
<span style='color: #7488ae'><i>       instructions have been specified --&gt;</i></span>
  <b>&lt;UpdateName&gt;</b>ChartPlugin<b>&lt;/UpdateName&gt;</b>
  <b>&lt;Version&gt;</b>2.1.0<b>&lt;/Version&gt;</b>
  <b>&lt;ReleaseDate&gt;</b>08/09/2009<b>&lt;/ReleaseDate&gt;</b>

  <span style='color: #7488ae'><i>&lt;!-- Operations --&gt;</i></span>
  <b>&lt;UpdateOperation&gt;</b>
    <b>&lt;Name&gt;</b>Copy<b>&lt;/Name&gt;</b>
    <b>&lt;Arg&gt;</b>libChartPlugin.so.2.1.0<b>&lt;/Arg&gt;</b>
    <b>&lt;Arg&gt;</b>$${APPDIR}<b>&lt;/Arg&gt;</b>
    <b>&lt;OnError</b><span style='color: #00892b'> Action=</span><span style='color: #aa0000'>"Abort"</span><b>/&gt;</b>
  <b>&lt;/UpdateOperation&gt;</b>

  <b>&lt;UpdateOperation&gt;</b>
    <b>&lt;Name&gt;</b>Copy<b>&lt;/Name&gt;</b>
    <b>&lt;Arg&gt;</b>ChartPlugin-2.1.0-Config.xml<b>&lt;/Arg&gt;</b>
    <b>&lt;Arg&gt;</b>$${APPDIR}/config<b>&lt;/Arg&gt;</b>
    <b>&lt;OnError</b><span style='color: #00892b'> Action=</span><span style='color: #aa0000'>"Abort"</span><b>/&gt;</b>
  <b>&lt;/UpdateOperation&gt;</b>

<b>&lt;/UpdateInstructions&gt;</b>
</pre>
\endhtmlonly

Click \ref kdupdater_updateinstructionsxml_fileformat to know more about the 
fileformat of UpdateInstructionsXML.

Before moving ahead, lets revisit the definition of UpdateInstructionsXML

\htmlonly
<center><table border="0" width="80%"><tr>
<td bgcolor="#ddddff" width="20px"></td>
<td width="*"><strong>Definition:<br><font color="blue">
UpdateInstructionsXML is a special file by name UpdateInstructions.xml contained
in an UpdateFile; that lists out the operations to perform inorder to install
an update.
</font></strong></td></tr></table></center>
\endhtmlonly

\section kdupdater_updateserverarch_summary Summary

In summary we can say

\li The update server has a directory into which all the updates are hosted. 
This directory is called UpdateDirectory.

\li The UpdateDirectory consists of an UpdateXML file and one or more 
UpdateFiles. 

\li UpdateXML describes the updates available in terms of name, title, 
description, version, release date, dependencies and their update files. It 
also (optionally) specifies a compatibility level against which the updates 
from this server can be downloaded and installed by the client.

\li UpdateFile is a compressed file that contains all the files and directories 
required to install the update on the client side.

\li One of the files contained in the UpdateFile is the UpdateInstructionsXML 
file. This file lists out the operations that must be performed on the client 
side to install the update.

The following diagram captures the structure of the update server directory.

\image html kdupdater_updateserversummary.png

*/

/**
\page kdupdater_updateclientarch KDUpdater - Update Client Architecture

\section kdupdater_updateclientarch_introduction Introduction

Update Client refers the the application within which the KDUpdater module is a 
part of. The architectural elements of the Update Client come from the KDUpdater
module itself. Users of KDUpdater only have to provide a few configuration
files/directories and runtime hints.

Update Client architecture can be understood interms of the following

\li \ref kdupdater_clientdirectory - The directory within which the client
application exists
\li \ref kdupdater_packagexml - A file that describes the packages currently
installed in the application.
\li \ref kdupdater_updatesourcesxml - A file that describes the location of
the update-servers from which updates are sourced.
\li \ref kdupdater_updatefinder - A module that looks for Updates, and 
downloads them.
\li \ref kdupdater_updateinstaller - A module that installs downloaded updates
\li \ref kdupdater_updateoperationfactory - A module that provides update
operations that are used while processing an Update's UpdateInstructionsXML.

\section kdupdater_clientdirectory  ClientDirectory

The update client is usually a part of another application, which would ideally
place all the files that it needs in a separate directory. This directory is
called “ClientDirectory”. 

\li On Windows XP it could be C:\\Program Files\\ApplicationName
\li On Linux it could be /usr/local/ApplicationName
\li On MacOSX it could be /Applications/ApplicationName

\htmlonly
<center><table border="0" width="80%"><tr>
<td bgcolor="#ddddff" width="20px"></td>
<td width="*"><strong>Definition:<br><font color="blue">
ClientDirectory is the directory within which the client application is 
available.
</font></strong></td></tr></table></center>
\endhtmlonly

\section kdupdater_packagexml PackageXML

PackageXML is a XML file that describes the packages that have currently been
installed in the application in terms of

\li Package name
\li Package title
\li Package description
\li Package version and release date
\li Package installation date

It also describes the application name, version and compatibility level that the
client application is in at the moment.

The PackageXML file should be stored in a file called Package.xml and must be
available as a top-level-file in the ClientDirectory. 

\htmlonly
<center><table border="0" width="80%"><tr>
<td bgcolor="#ddddff" width="20px"></td>
<td width="*"><strong>Definition:<br><font color="blue">
PackageXML describes the packages installed in the client application
</font></strong></td></tr></table></center>
\endhtmlonly

Shown below is a sample PackageXML file

\htmlonly   
<pre>
<span style="font-weight: bold;color: #000000;">&lt;Packages&gt;</span>
<span style="color: #000000;">    </span>
<span style="color: #000000;">    </span><span style="font-weight: bold;color: #000000;">&lt;AppName&gt;</span><span style="color: #000000;">VTKDesigner2</span><span style="font-weight: bold;color: #000000;">&lt;/AppName&gt;</span>
<span style="color: #000000;">    </span><span style="font-weight: bold;color: #000000;">&lt;AppVersion&gt;</span><span style="color: #000000;">2.0</span><span style="font-weight: bold;color: #000000;">&lt;/AppVersion&gt;</span>
<span style="color: #000000;">    </span><span style="font-weight: bold;color: #000000;">&lt;CompatLevel&gt;</span><span style="color: #000000;">3</span><span style="font-weight: bold;color: #000000;">&lt;/CompatLevel&gt;</span>
<span style="color: #000000;">    </span>
<span style="color: #000000;">    </span><span style="font-weight: bold;color: #000000;">&lt;Package&gt;</span>
<span style="color: #000000;">        </span>
<span style="color: #000000;">        </span><span style="font-weight: bold;color: #000000;">&lt;Name&gt;</span><span style="color: #000000;">MainWindow</span><span style="font-weight: bold;color: #000000;">&lt;/Name&gt;</span>
<span style="color: #000000;">        </span><span style="font-weight: bold;color: #000000;">&lt;Title&gt;</span><span style="color: #000000;">Main Window Shell</span><span style="font-weight: bold;color: #000000;">&lt;/Title&gt;</span>
<span style="color: #000000;">        </span><span style="font-weight: bold;color: #000000;">&lt;Description&gt;</span>
<span style="color: #000000;">            The main window into which all the components are hosted</span>
<span style="color: #000000;">        </span><span style="font-weight: bold;color: #000000;">&lt;/Description&gt;</span>
<span style="color: #000000;">        </span><span style="font-weight: bold;color: #000000;">&lt;Version&gt;</span><span style="color: #000000;">1</span><span style="font-weight: bold;color: #000000;">&lt;/Version&gt;</span>
<span style="color: #000000;">        </span><span style="font-weight: bold;color: #000000;">&lt;LastUpdateDate&gt;</span><span style="color: #000000;">01/11/2007</span><span style="font-weight: bold;color: #000000;">&lt;/LastUpdateDate&gt;</span>
<span style="color: #000000;">        </span><span style="font-weight: bold;color: #000000;">&lt;InstallDate&gt;</span><span style="color: #000000;">02/02/2008</span><span style="font-weight: bold;color: #000000;">&lt;/InstallDate&gt;</span>
<span style="color: #000000;">        </span>
<span style="color: #000000;">    </span><span style="font-weight: bold;color: #000000;">&lt;/Package&gt;</span>
<span style="color: #000000;">    </span>
<span style="color: #000000;">    </span><span style="font-style: italic;color: #808080;">&lt;!-- More Package elements --&gt;</span>
<span style="font-weight: bold;color: #000000;">&lt;/Packages&gt;</span></pre>
\endhtmlonly 

Click \ref kdupdater_packagexml_fileformat to know more.


\section kdupdater_updatesourcesxml UpdateSourcesXML

The UpdateSourcesXML file describes all the sources from where updates can be
fetched. Against each source certain meta-information is provided to describe
the source along with the complete location of the source’s update server. The
UpdateSourcesXML file should be stored in a file called UpdateSources.xml and
must be available as a top-level file in the ClientDirectory.

\htmlonly
<center><table border="0" width="80%"><tr>
<td bgcolor="#ddddff" width="20px"></td>
<td width="*"><strong>Definition:<br><font color="blue">
UpdateSourcesXML primarily describes the locations of update sources.
</font></strong></td></tr></table></center>
\endhtmlonly

Shown below is a sample UpdateSourcesXML file.

\htmlonly
<pre>
<span style="font-weight: bold;color: #000000;">&lt;UpdateSources&gt;</span>
<span style="color: #000000;">    </span>
<span style="color: #000000;">    </span><span style="font-weight: bold;color: #000000;">&lt;UpdateSource&gt;</span>
<span style="color: #000000;">        </span>
<span style="color: #000000;">        </span><span style="font-weight: bold;color: #000000;">&lt;Name&gt;</span><span style="color: #000000;">KDABUpdateServer</span><span style="font-weight: bold;color: #000000;">&lt;/Name&gt;</span>
<span style="color: #000000;">        </span><span style="font-weight: bold;color: #000000;">&lt;Title&gt;</span><span style="color: #000000;">Updates from KDAB</span><span style="font-weight: bold;color: #000000;">&lt;/Title&gt;</span>
<span style="color: #000000;">        </span><span style="font-weight: bold;color: #000000;">&lt;Description&gt;&lt;/Description&gt;</span>
<span style="color: #000000;">        </span><span style="font-weight: bold;color: #000000;">&lt;Url&gt;</span><span style="color: #000000;">https://www.kdab.net/updates/vtkdesigner2</span><span style="font-weight: bold;color: #000000;">&lt;/Url&gt;</span>
<span style="color: #000000;">        </span>
<span style="color: #000000;">    </span><span style="font-weight: bold;color: #000000;">&lt;/UpdateSource&gt;</span>
<span style="color: #000000;">    </span>
<span style="color: #000000;">    </span><span style="font-weight: bold;color: #000000;">&lt;UpdateSource&gt;</span>
<span style="color: #000000;">        </span>
<span style="color: #000000;">        </span><span style="font-weight: bold;color: #000000;">&lt;Name&gt;</span><span style="color: #000000;">VCreateLogicServer</span><span style="font-weight: bold;color: #000000;">&lt;/Name&gt;</span>
<span style="color: #000000;">        </span><span style="font-weight: bold;color: #000000;">&lt;Title&gt;</span><span style="color: #000000;">Updates from VCreate Logic</span><span style="font-weight: bold;color: #000000;">&lt;/Title&gt;</span>
<span style="color: #000000;">        </span><span style="font-weight: bold;color: #000000;">&lt;Description&gt;&lt;/Description&gt;</span>
<span style="color: #000000;">        </span><span style="font-weight: bold;color: #000000;">&lt;Url&gt;</span><span style="color: #000000;">https://www.vcreatelogic.com/updates/vtkdesigner2</span><span style="font-weight: bold;color: #000000;">&lt;/Url&gt;</span>
<span style="color: #000000;">        </span>
<span style="color: #000000;">    </span><span style="font-weight: bold;color: #000000;">&lt;/UpdateSource&gt;</span>
<span style="color: #000000;">    </span>
<span style="font-weight: bold;color: #000000;">&lt;/UpdateSources&gt;</span></pre>
\endhtmlonly

Click \ref kdupdater_updatesources_fileformat to know more.


\section kdupdater_updatefinder UpdateFinder

Update finder is a module that

\li Reads the PackageXML to figure out the packages installed in the application

\li Reads the UpdateSourcesXML to figure out the locations of the update
servers. From each server the latest copy of the UpdateXML file is downloaded to
a local temporary directory

\li Compares the PackageXML and UpdateXML file(s) and creates a list of updates
and new packages available for installation

\li If updates are available, it signals the availability of the updates and
makes available information about the updates via a software interface.

\htmlonly
<center><table border="0" width="80%"><tr>
<td bgcolor="#ddddff" width="20px"></td>
<td width="*"><strong>Definition:<br><font color="blue">
UpdateFinder is a software module that finds available updates and signals
the host application about it.
</font></strong></td></tr></table></center>
\endhtmlonly

Finding of updates can be triggered by developer. Read the class documentation 
of \ref KDUpdater::UpdateFinder to know more.

\section kdupdater_updateinstaller UpdateInstaller

The UpdateInstaller module installs one or more named updates by

\li Validating the availability of the update

\li Resolving dependencies of each update (and confirming their installation if
required)

\li Downloading the required UpdateFile

\li Uncompressing the UpdateFile and executing the operations contained in the
UpdateInstructionsXML file. The actual operations are performed by making use of
the UpdateOperationFactory module (described next), but the UpdateInstaller has
to orchestrate the actuation of operations.

\htmlonly
<center><table border="0" width="80%"><tr>
<td bgcolor="#ddddff" width="20px"></td>
<td width="*"><strong>Definition:<br><font color="blue">
UpdateInstaller is a module that downloads installs one or more named updates
</font></strong></td></tr></table></center>
\endhtmlonly

It must be noted at this point that the UpdateInstaller may reside within the
host application or within a separate updater process. Sometimes, atleast on
Windows, the UpdateInstaller may have to replace files that are being used by
the application. In such cases the installation of the update has to be deferred
until the application is restarted.

\section kdupdater_updateoperationfactory UpdateOperationFactory

As described in \ref kdupdater_updateinstructionsxml, installation of updates 
is done by executing one or more update instructions. These update instructions 
are known as update operations. Each update operation is an implementation of
\ref KDUpdater::UpdateOperation. UpdateOperations

\li Knows how to perform the operation

\li Knows how to undo the performed operation

\li Knows how to backup files before performing the operation. This backup can
be used while undoing the operation

\li The \ref KDUpdater::UpdateOperationFactory is a factory class that can serve
\ref KDUpdater::UpdateOperation modules based on their names.

\htmlonly
<center><table border="0" width="80%"><tr>
<td bgcolor="#ddddff" width="20px"></td>
<td width="*"><strong>Definition:<br><font color="blue">
UpdateOperationFactory makes available UpdateOperation modules based on
their name.
</font></strong></td></tr></table></center>
\endhtmlonly

By default the following update operations are provided

\li Copy
\li Delete
\li Rename
\li AppendFile
\li PrependFile
\li InstallUpdateOperation
\li UninstallUpdateOperation

Additional operations can be installed and uninstalled at run-time. It is also
possible to install and uninstall update operation modules during the update
process. This means that updates can contain UpdateOperation(s) that can be
activated and used with newwer updates.

\section kdupdater_clientsummary Summary

- The update client is a part of the client application.
- ClientDirectory is a directory on the local file system where files
belonging to all the installed packages are stored
- Within the ClientDirectory are two special files: PackageXML and
UpdateSourcesXML
- PackageXML describes installed packages 
- UpdateSourcesXML provides information about the update sources. The most
important information provided by this file is the locations of the UpdateServer
corresponding to the update sources
- UpdateFinder can be programmed to look for updates. This module 
    -# parses PackageXML and UpdateSourcesXML files
    -# creates a list of updates and new modules that can be installed
    -# signals the host application about the availability of updates
- The host application can then use one or more widgets supplied by the
UpdateInstaller module to allow the user to select the updates to install; or it
can choose to install all the updates.
- The UpdateInstaller module performs the actual installation of the updates
by
    -# Resolving dependencies between updates
    -# Downloading UpdateFile(s) from the update source
    -# Uncompressing UpdateFile(s) and executing the instructions contained in
       the UpdateInstructionsXML file by making use of update operations
       provided by UpdateOperationsFactory

The following diagram shows the key components of the UpdateClient.

\image html kdupdater_updateclientsummary.png

*/ 




